<html>
<head>
<link href="//maxcdn.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.min.css" rel="stylesheet">
<title>Jade &mdash; JAvascript Design Environment</title>
<style>
body {
  width: 650px;
  font: 16px/1.5 Georgia,serif;
}
.aspect {
  font-variant: small-caps;
}
.test {
  white-space: pre;
  font: 12px/1.25 "Lucida Console",Monaco,monospace;
  margin-left: 10px;
  padding: 5px;
  background-color: #EEEEEE;
}
tt {
  font: 12px/1.25 "Lucida Console",Monaco,monospace;
}
</style>
</head>
<body style="width:650px;">
<h2>Jade &mdash; JAvascript Design Environment</h2>

<p><h3>Quick start</h3>

<ul>
<li>See the README for the 6004x/jade github repo for setting up a
local copy of Jade for development use.
<li>Tool tips, etc., appear in status bar below the diagram
<li>Click on <i class="fa fa-fw fa-pencil-square-o"></i> and type the name of a module to create
or edit, e.g., "/user/foo", then click OK.
Modules names look like file pathnames (/x/y/z) where the hierarchy is used to display
the parts bin in organized way.
The "/analog/..." and "/gates/..." modules are loaded automatically.
<li>Click and drag a couple of components from the parts bin.  You can move components
by clicking and dragging them to a new location.  You can select multiple components by
clicking on the background and dragging out a selection rectangle.
<li>Delete selected components by typing DEL
<li>There's a clipboard, accessible via <i class="fa fa-fw fa-cut"></i>, <i class="fa fa-fw fa-copy"></i>, <i class="fa fa-fw fa-paste"></i>
<li>Rotate/flip selected components using <i class="fa fa-fw fa-arrows-h"></i>, <i class="fa fa-fw fa-arrows-v"></i>, <i class="fa fa-fw fa-rotate-right"></i>, <i class="fa fa-fw fa-rotate-left"></i>
<li>Double click a component to edit its properties
<li>Add wires by clicking on the open circle at component terminals or
ends of wires, drag to create a wire
<li>You can associate a signal name with a wire either by connecting it to a named
port component or by double-clicking the wire.  Wires with the same signal name are
considered electrically connected.
<li>There is undo/redo support using <i class="fa fa-fw fa-reply"></i>, <i class="fa fa-fw fa-share"></i>
<li>Saves are automatic (every 25 edits, when changing modules or when leaving
the browser window).
<li>To toggle the diagram grid for screen shots of schematics: Click on <i class="fa fa-fw fa-th"></i>.
</ul>

<p><h3>Overview</h3>

<p>Jade provides a framework for editing and simulating hierarchical
block diagrams.  The editing and simulation tools are provided by
plug-ins, so it's easy extend the framework to support different
types of diagrams.

<p>The basic building block is a <i>module</i>.  Each module has one
or more <i>aspects</i>, which can be edited using one of the supplied
editing tools.  Currently Jade has editors for the following aspects:

<ul>
<p><b class="aspect">schematic</b>.  A circuit diagram incorporating
components (instances of other modules) with wires that run between
the component terminals.  Basic components (ground, vdd, ports,
jumpers, text) are available on the toolbar; other components from
the loaded module collections are available in the parts bin.  The toolbar
also has icons for the simulation tools (dc analysis, ac analysis,
transient analysis and module test).  It's possible
to specify that the parts bin show only particular parts and the
toolbar show only a subset of the tools.

<p><b class="aspect">icon</b>.  When a schematic contains an instance of a module as
a component, what appears in the diagram is the module's icon, usually
a simple shape representing the component's functionality along with
terminals that allow connections to be made to the component's ports.

<p><b class="aspect">properties</b>.  Modules have properties (key:value pairs) that
further specify the behavior of a module, e.g., the resistor module
has a "resistance" property specifying the component's resistance.
Properties have default values, which can be overriden for each
instance of the module.

<p><b class="aspect">test</b>.  The test tool runs a simulation, providing a
sequence of values for module's inputs and verifying that the
expected values appear on the module's outputs.  The test aspect
provides the information needed to run the test.

</ul>


<p><h3>Extracting a netlist</h3>

<p>To run the simulation tools on a module's schematic, Jade converts
the (possibly hierarchical) schematic into a flattened netlist that
has one entry for each primitive component listing its properties and
the signals connected to its terminals.  The netlister is given a list
of primitive component modules and stops its hierachical descent when
one of these components is reached.

<p>The extraction process has several steps:

<ol>
<p><li>Label each connection with its associated list of signal
names.  Signal names are determined by port components or the signal
name property, if any, given to a wire.  Signal names can include
lists of names and/or iterators (see below).  If a wire is unnamed,
Jade will generate a name to use for the netlist.

<p><li>Ensure each component in the diagram has a unique name, generating
a name for components whose name properties have not been set by the user.

<p><li>Generate a netlist entry for each primitive component (instances
from the /analog collection for device-level simulation, instances from the 
/gates collection for gate-level simulation).  Depending on the signal lists
associated with the component's terminals, more than one netlist entry
may be generated; see below.

<p><li>Recursively generate a netlist entry for each hierarchical component,
where the signal names connected to the component's terminals become the
signal names for wires connected to the corresponding ports in the
component's schematic.  The component's internal signals will be prefixed
with the component's name.  When the hierarchy is several levels deep,
the prefix reflects the pathname created by concatenating the names of
the components as extractor descended the hierarchy, e.g., <tt>alu.adder.cin</tt>.

</ol>

<p>Signal names should consist of letters, numbers and _.  For compound
signals (e.g., a bus) one can specify a comma-separated list of names

<div class="test">a[3],a[2],a[1],a[0]</div>

<p>You can use an iterator suffix of the form "[<i>start</i>:<i>end</i>]" or
"[<i>start</i>:<i>end</i>:<i>step</i>]" which Jade expands into the
appropriate comma-separated list.  Examples:

<div class="test">a[3:0] &rarr; a[3],a[2],a[1],a[0]
b[7:0:3] &rarr; b[7],b[4],b[1]
c[30:0],gnd &rarr; c[30],c[29],&hellip;,c[1],c[0],gnd
d[3:2][1:0] &rarr; d[3][1],d[2][1],d[3][0],d[2][0]
</div>

<p>Finally, you can use a replicator suffix of the form "#<i>count</i>" which
will cause Jade to replicate the prefix the specified number of times.
Examples:

<div class="test">gnd#2 &rarr; gnd,gnd
a[1:0]#2 &rarr; a[1:0],a[1:0] &rarr; a[1],a[0],a[1],a[0]
</div>

<p>Note that multiple suffixes are processed right-to-left.

<p>A single component instance may generate several netlist entries. The width W
of each terminal in a component is determined from its label, e.g., a terminal
with a label of "foo" has W=1, a label of "sel[2:0]" has W=3.  When the
netlist for a component is generated, each of its terminals consumes W entries
from its associated signal list.  Jade will generate N components where 

<p>N = max over all terminals(length_of_terminal's_signal_list / terminal's_W)

<p>If N*W is longer than a terminal's associated signal list, the list gets reused
in a cyclic fashion.  It's a bit hard to explain in words but the results tend
to match your expectations.  For example, the following schematic using a 2-input
XOR gate

<p><img src="help_1.png" height="75">

<p>will expand into the following 32 2-input XOR gates:

<p><img src="help_2.png" height="75">

<p>Note that it is an error if (N mod W) is nonzero for any terminal.


<p><h3>Device-level simulation</h3>

<p>The device-level simulation tool expects a flattened netlist containing
components from the /analog collection.

<p>When simulating digital circuits, the easiest way to run
device-level transient simulations is to create
a <span class="aspect">test</span> aspect specifying

<p><tt>.mode device</tt>

<p>and then use the <span class="fa fa-fw fa-check" style="color:green;"></span>
tool to run the test.  This tool will create the appropriate voltage
sources to generate the specified input waveforms, run the simulation
long enough to process all the test vectors, then examine the
simulation results to ensure the outputs have the specified values as
the specified time.  The test tool will optionally plot waveforms for
the specified nodes.

<p>One can also use primitive components to generate input waveforms
(using voltage and current sources) and examine output waveforms
(using voltage and current probes).  After including the appropriate
sources and probes, the following types of circuit analysis can be
performed.

<ul>
<tt>DC</tt>: Using the t=0 value for all sources, iteratively
determine the operating point of the circuit.  Note that on some
circuits, the iteration may not converge on stable values for node
voltages and branch currents; you may find adding initial-voltage
components (usually on feedback nodes) will allow the analysis to
coverge.  The operating voltage for each node and current through each
voltage probe will be displayed on the schematic.

<p><tt>AC</tt>: Determine the small signal response at the probed
nodes with respect to source specified in the AC setup dialog.  The
response is calculated at different frequencies over the range
specified in the setup dialog.  The phase (in degrees) and magnitude
(in dB) of the response is plotted as a function of log(Hz).

<p><tt>TRAN</tt>: Determine the transient response of the circuit from
t=0 to the end time specified in the TRAN setup dialog.  The resulting
waveforms are plotted as function of time for the voltage and current
probes.  Note that the time to complete the simulation grows quickly
with increasing circuit size -- there's a practical limit of a few
tens of circuit nodes.  The simulation proceeds by using a sequence
of linear approximations of circuit operation over a small time step.
The size of each time step is made small enough to ensure that
the error introduced by the linear approximation at that step is small.

</ul>

<p><h3>Gate-level simulation</h3>

<p>The gate-level simulation tool expects a flattened netlist containing
components from the /gates collection.

<p>When simulating digital circuits, the easiest way to run gate-level
simulations is to create a <span class="aspect">test</span> aspect
specifying

<p><tt>.mode gate</tt>

<p>and then use the <span class="fa fa-fw fa-check" style="color:green;"></span>
tool to run the test.  This tool will create the appropriate voltage
sources to generate the specified input waveforms, run the simulation
long enough to process all the test vectors, then examine the
simulation results to ensure the outputs have the specified values as
the specified time.  The test tool will optionally plot waveforms for
the specified nodes.

In gate-level simulation, node values are one of the following:

<ul>
0, 1 &mdash; the two binary values<br>
X &mdash; an unknown or illegal logic value<br>
Z &mdash; not driven, aka "high impedance"
</ul>

<p><h3>Testing</h3>

<p>The <span class="aspect">test</span> aspect makes it easy to test the functionality
of a module.  Here's a test for an XOR circuit with inputs A and B, and output Z:

<div class="test">// set up Vdd, establish signaling voltages
.power Vdd=1
// Vol, Voh set voltages generated for input signals
// Vil, Vih set voltage thresholds for determining logic values
.thresholds Vol=0 Vil=0.1 Vih=0.9 Voh=1

// test actions are applied to named groups of signals.
// A signal can appear in more than one group.  Order
// of groups and signals within each group determine 
// order of values on each line of test values
.group inputs A B
.group outputs Z

// set type of simulation to be performed
//  device -- transient simulation; components must be from from /analog
//  gate -- gate-level simulation; components must be from /gates
.mode device

/*
Tests are sequences of lines supplying test values; .cycle specifies
the sequence of actions that will be performed for each test.  Available
actions are
   assert <i>group</i> -- set values for signals in <i>group</i> with H,L test values
   deassert <i>group</i> -- stop setting values for signals in <i>group</i> with H,L test values
   sample <i>group</i> -- check values of signals in <i>group</i> with 0,1 test values
   tran <i>time</i> -- run simulation for specified time interval
   <i>signal</i>=<i>val</i> -- set signal to specified value
*/
.cycle assert inputs tran 9n sample outputs tran 1n

// the tests themselves -- one test per line
//   to assert signal this cycle use 0,1; use Z or - if not to be asserted
//   to sample signal this cycle use L,H; use - if not to be sampled
// whitespace can be used to improve readability, non-blank characters
// are associated, in order, with signals listed in .group above.
00 L
01 H
10 H 
11 L

// (optional) produce plots showing the test inputs and/or outputs
.plot A B
.plot Z
</div>

<p>The tests for a module can be run by clicking <span class="fa fa-fw fa-check" style="color:green;"></span> in the <span class="aspect">schematic</span> toolbar.

<p>If you'd like to see more examples, each module in the /gates
collection has a test aspect that verifies its functionality at the
device level.

</body>
</html>
